云变量API文档
通用存储、列表、货币、名字:这些功能统称为云变量(在部分老文档里,也把这部分功能统称为积分)
所有云变量接口都运行在协程内, 所以调用者必须确保自己处于协程中, 每个和远程服务(RPC)交互的操作调用后都会等待直到处理结果返回.
几乎所有接口的参数都有且只有一个table
(少数接口没有任何参数)
返回结果通常有三个值, 分别是error_code
, data
, err_msg
error_code
: 为0时, 代表操作成功. 否则将被视为有某种错误data
: 当error_code == 0
时, data是本次操作的结果. 否则, data可能是服务器 方面的某种错误原因, 也可能为nil. 所以使用data前, 一定要先判断error_code
是否为0err_msg
: 当error_code == 0
时, err_msg为nil, 否则err_msg为一个字符串, 描述错误信息
-- coroutine.async可以创建一个协程. 以下假设所有调用都处于协程之内, 不再使用coroutine.async包裹
coroutine.async(function()
local error_code, data, err_msg = score.get({
user_id = '123456',
key = 'bar',
})
if error_code == 0 then
log.info(fmt("数据: %s, json.encode(data"))
else
log.error(fmt("错误码: %s, 错误数据: %s, 错 误信息: %s", ec, json.encode(data), err_msg))
end
end)
注意:
- 每个游戏局在现实时间每分钟(从第一次提交开始计时,并非严格意义上的分钟)内,最多执行300次读操作和300次写操作。
- 云变量单次读写不得超过32M,每分钟写入操作总大小不得超过48M。
- 写操作次数=commit的次数+message_send的次数+message_modify_read的次数+message_delete的次数。
通用接口
get_commit (非RPC)
获得一个提交对象。除了统计,所有的修改操作都必须在提交对象上进行。可以把有关联的,必须同时成功的修改操作放在同一个提交对 象里。
local c = score.get_commit()
commit
结束之前获得的提交对象,真正提交所有修改。在commit函数返回之前,所有相关修改未必真正的写入了数据库。
-- 示例
local c = score.get_commit()
-- 设置apple的初值为5
c.set {user_id = 55555555, key = 'apple', i_value = 5}
-- 添加2个apple
c.addi {user_id = 55555555, key = 'apple', value = 2},
-- 设置apple的属性
c.set {user_id = 55555555, key = 'apple', value = {color = 'red', price = 100}
-- 设置hp初值为100, 且设置'魔障'属性
c.set {user_id = 55555555, key = 'hp', value = {['魔障'] = 10}, i_value = 100}
-- 增加1000 HP
c.addi {user_id = 55555555, key = 'hp', value = 1000},
-- 扣除'星辰之力' 2点.
-- 注意, 如果value = 2改为 value = 4, 那么本次commit会失败, 因为'星辰之力'不足, 整个committer里的所有操作都无效化
c.money_cost {user_id = 55555555, key = '星辰之力', value = 2}
c.world_list_add({user_id = 55555555, key = '砖', value = {a = 1}, world_id = 777})
c.world_data_set({user_id = 55555555, key = '种子', value = {b = 1}, world_id = 777})
local error_code, data, err_msg = c.commit()
if error_code == 0 then
log.info('写入数据成功')
else
log.error(fmt('写入失败, 错误码: %s, 错误信息: %s, 额外错误信息: %s', error_code, err_msg, json.encode(data)))
end
user_id
是number类型, 比如55555555
, 不过通常你也可以传入字符串形式的"55555555"
, 但是要保证该字符串可以被合法的转为number- response里的
user_id
总是number key
是一个字符串, 代表二级分类. 比如:
{user_id = 45646546, key = '装备', value = {'手榴弹' = 3, '子弹' = 1053, 'AK47' = 1}}
- 参数
- 无
- 返回的data格式
data = {} -- 空table
test_cloud_value
检测该值是否可以存进云变量,并返回序列化后的字节数。如果待检测的值合法,则打印序列化后的长度;否则报错提示非法原因。
-- 示例
local map = __TS__New(
Map,
{
__TS__Keyword("number"),
__TS__TypeReference(Unit, {})
},
__TS__New(Array, {{kind = "TupleType"}})
)
map.set(1, base.player(1):get_hero())
-- error_code返回0表示可以存储,其他值为不可存储
-- length为云变量序列化后的长度
-- err_msg为错误信息
-- 运行这句会报错:参数含有Map或Set等无法上传的对象
local error_code, length, err_msg = score.test_cloud_value { value = map }
通用存储
score.get
查询数据
local error_code, data, err_msg = score.get({
user_id = '55555555', -- 也可以用字符串, 但要保证可以合法转为number, 下同
key = 'apple',
})
如果调用成功, 则返回的data
为
-- 示例
data = {
{
i_value = 7,
key = "apple",
user_id = 55555555,
value = {
color = "red",
price = 100
}
}
}
user_id
: number, 但是也可以传入一个number[]类型, 做批量查询key
: 字符串, 但是也可以传入一个string[]类型, 做批量查询
user_id
和key
可以同时都是数组, 实现复合查询
committer.set
设置云变量
local c = score.get_commit()
c.set {
user_id = '55555555',
key = '属性',
value = {['攻击'] = 10, ['护甲'] = 20},
i_value = 100,
s_value = '必胜!',
}
local error_code, data, err_msg = c.commit()
- 参数
user_id
和key
: 上文已经解释value
: 可选, 是一个table, 应遵守云变量的值规则i_value
: 可选, 是一个number, 会四舍五入成整数s_value
: 可选, 是一个string
可以每次设置value/i_value/s_value中的一个或多个。设置多个值时,会按照i_value、s_value、value的顺序依次执行。比如传入的是
c.set {
user_id = 55555555,
key = '属性',
i_value = 100,
s_value = '必胜!',
}
则只会设置i_value和s_value, value不会受到任何影响(以前设置过就不变, 没设置过就保持为nil)。
注意: 如果i_value不是数字,会直接报错attempt to add a 'string' with a 'number'
,整条提交全部回滚。
committer.c.add
累加数字到i_value
c.add {
user_id = '55555555',
key = 'hp',
i_value = 1,
}
这会使i_value加到{user_id = '55555555', key = 'hp'}
的行
如果该行不存在, 则视同committer.set
操作
金钱存储
特属于通用存储, 金钱存储内只有数字字段, 且消费时不能使存额降为负值(会使commit()操作失败)
score.money_get
查询金钱
local ec, data, err_msg = score.money_get({
user_id = '55555555',
key = '星辰之力',
})
如果调用成功, 则返回的data
为
data = {
{
key = "星辰之力",
user_id = 55555555,
value = 1
}
}
user_id
和key
的意义与score.get
里的user_id
与key
相同, 都可以传入数组